Documentation

Demo - Turtle 3D - Open Dev Kit Documentation

Open Dev Kit Documentation :: Demo - Turtle 3D

Demo project showcasing 3D robotics with physics taught through simple Lua scripts; great resource for students learning how to program. Users can control a turtle (or other spawned Actor objects) through script-based commands, enabling movement, rotation, colors, and physics interactions. The environment includes multiple UI Windows for scripting, monitoring object properties, and adjusting Scene settings such as lighting, gravity, and camera perspective.

How it Works

  • Demo Initialization
      The demo starts with a turtle already placed in a 3D environment. The interface includes multiple UI Windows: the Main view, where the scene is rendered; the Controls window, which allows users to build Lua scripts for programming the turtle; the HUD window, displaying various properties about the selected object; and the Object Spawner window, which shows up when creating new objects. A secondary Preview Scene is loaded for the HUD's top-down view. The additional windows are loaded via the Start function which executes upon starting the demo.
  • Programming Spawned Objects
      Users interact with the Controls Window, which provides pre-defined command buttons that insert Lua script lines into a Textbox. Alternatively, users can also write their own Lua scripts directly. Changing the script, or clicking Run Script if Auto Execute is not ticked, will cause the script to execute the commands linearly via Lua evaluation, instructing the turtle (or any spawned object) to move, rotate, draw a line on its path, or perform other programmed actions. You can edit the line's properties via the DefaultLine variable found in Tools > Globals / API.

      Commands follow a structured format using Lua scripting. Each command targets a specific object using its actor ID within the Objects Array and applies a function to modify its state.
      Command Structure: Objects[x]:COMMAND(parameters)
      • x = The actor ID, which identifies the specific object to control.
      • COMMAND = The action to perform (e.g. movement, rotation).
      • parameters = Additional values required for the command.
  • Spawning a New Object
      You can spawn new objects by clicking New in the Controls Window, which opens the Object Spawner. This Window allows setting properties for that object such as name, its graphic model, position, scale, color and physics. After configuring the settings, clicking Spawn Object will add the new actor to the Scene, where it can be controlled via Lua commands using its unique identifier number.

Adding New Spawnable Objects

Follow these steps to add a new object to the demo:

  1. Create the New Object:
    1. Open Tools > Resources.
    2. Double-click the Sprites Sprite Resource.
    3. Select an empty tile and click the Import Images/Model icon to import your graphic model. You may have to configure its scale and rotation.
    4. Depending on the shape of the model you are importing, click the Add Box Collision/Add Capsule Collision icon ("Shared with whole Tile") to add a new collision box to the Sprite Editor.
    5. Line it up with the model.
  2. Set up the New Shape:
    1. Open Tools > Globals / API.
    2. Select the ObjectTemplates variable.
    3. Since there is now a new object, we will increase the Default Object count by clicking + once beside Default Object.
    4. Head down until you find the new entry (labeled "[9]") and set its Sprite Tile to 6 if the new object was created on the 7th tile (the count starts from 0, therefore the 7th tile's # would be 6).
    5. Configure the rest of its properties as you see fit.
  3. Test the Game:
      That's it! Run the project to verify the new object is now selectable in the Object Spawner Window's dropdown list.

Adding a New Command: Set Color

Follow these steps to add a new command to the demo for changing the color of an object:

  1. Update API:
    1. Open Tools > Globals / API.
    2. Create a new function for the Object class called SetColor.
    3. Add a function parameter for that function called Color, and set its type to Root.ColorHDR.
    4. Click Edit Function Script to add color-changing functionality using the Change Tint Color function (found under the Actor category or by using the search filter):
      • Identifier = this
      • Value = Color
  2. Create the New Command Button:
    1. Open the Controls Window.
    2. Since this command is about color, we can simply copy-paste the btnDrawColor Button and only do minor changes to it, considering it has very similar functionality.
    3. Update the Button's Clicked Event:
      • Set Change Text's value to txtScript.Text & "\n" & "Objects[" & lbCurrentObject.SelectedIndex + 1 & "]:SetColor(Root.ColorHDR(" & GUI.ColorDialogSelectionHDR.Red & "," & GUI.ColorDialogSelectionHDR.Green & "," & GUI.ColorDialogSelectionHDR.Blue & "," & GUI.ColorDialogSelectionHDR.Alpha &"));"
      4. Essentially, we're just changing the ... + 1 & "]:_Set_DrawColor(Root.ColorHDR ... part of the value to ... + 1 & "]:SetColor(Root.ColorHDR ... so it reflects the name of the new function we created, which is "SetColor".
  3. Test the Application:
      Run the project to verify the new command works as expected.

Sample Scripts

Copy these scripts into the Lua textbox of the Controls Window to see them draw various things.

Squigly Cylinder

Objects[1]:_Set_Drawing(1);
local a = 0
while a < 18 do
Objects[1]:_Set_DrawColor(Root.ColorHDR(a / 18,1,1,1));
Objects[1]:Elevate(100);
Objects[1]:Forward(20);
Objects[1]:RotateLeft(10);
Objects[1]:Descend(100);
Objects[1]:Forward(20);
Objects[1]:RotateLeft(10);
a = a + 1;
end

Circle

Objects[1]:_Set_Drawing(1);
local a = 0
while a < 360 do
Objects[1]:Forward(2);
Objects[1]:RotateLeft(1);
a = a + 1;
end

Square

Objects[1]:_Set_Drawing(1);
Objects[1]:Teleport(Root.Vector3(-250,0,0));
Objects[1]:Forward(500);
Objects[1]:RotateLeft(90);
Objects[1]:Forward(500);
Objects[1]:RotateLeft(90);
Objects[1]:Forward(500);
Objects[1]:RotateLeft(90);
Objects[1]:Forward(500);

Chaotic

Objects[1]:_Set_Drawing(1);
Objects[1]:Teleport(Root.Vector3(0,-250,0));

local a = 0
local b = 0

while b < 375 do
Objects[1]:Forward(a);
Objects[1]:RotateRight(b);
a = a + 3
b = b + 1
end

Spiral

Objects[1]:_Set_Visible(1);
Objects[1]:_Set_Drawing(1);

local a = 0

while a < 1080 do
Objects[1]:_Set_DrawColor(Root.ColorHDR(a/1080,a/1080,a/1080,1));

Objects[1]:Forward(a);
Objects[1]:RotateLeft(59);
a = a + 1;
end

Fractal

Objects[1]:_Set_Drawing(1);
Objects[1]:Teleport(Root.Vector3(0,600,0));
Objects[1]:RotateLeft(90);
Objects[1]:FractalTree(200,30,7);

If you think anything is missing, please feel free to: submit documentation feedback on this page